Developer CD Series 1995 June: Reference Library

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1995 June: Reference Library / Dev.CD Jun 95 / Dev.CD Jun 95.toast / What's New? / New System Software Extensions / QuickDraw 3D ß / Programming / Convert Sources from Pre Beta / Release Notes QD3D B1C1

Wrap

Text File | 1995-03-16 | 11.9 KB | 592 lines | [TEXT/ttxt]

Welcome to the B1C1 QuickDraw 3D Release Installation Note that there are five shared libraries that make up the QuickDraw 3D package and which should be installed in your Extensions folder: QuickDraw™ 3D QuickDraw™ 3D Accel. Mgr. QuickDraw 3D™ Soft. Rast. QuickDraw™ 3D Viewer ControllerCore Your application only needs to link against QuickDraw™ 3D. New in this release is the 3D Viewer, which similar to the QuickTime movie controller, but it lets you manipulate 3D objects. You don’t need to know any QD3D calls to make use of it and it only takes 5 calls to add it to your application. If you want to use it, you need to link against QuickDraw™ 3D Viewer. As always, please “weak link” your apps and determine if they are installed by checking that the entry point to the QD3D library has been loaded, see page 98 of Develop 21. Changes • QuickDraw 3D now does it memory allocation out Multifinder Temp memory. This gives you total control over your heap and you can make the size of your application’s heap as small as you need it to be for your requirements. Note that in the case where we run out/can’t allocate out of the temp memory, we will post an “out of memory” warning and start allocating out of your application’s heap (we will continue posting the warning every time we allocate out of your heap). When we run out of memory, we will post an error, not a warning. • We have further collapsed the headers from previosu releases, all geometries can now be found in QD3DGeometry.h. Name changes - The enclosed MPW canon script will apply all the name changes that are part of Beta. Here is a description of the changes: • All routines names were changed from Er to Q3. • All types were changed from Et to TQ3, with the underscores in the names removed. • All constants were changed from Ec to kQ3, with the underscores in the names removed. • Functions that ended with _Draw, _Pick, were replaced by _Submit. Whether you are doing drawing, picking, or bounding box operations is determined by the Q3View_StartFoo call (Q3View_StartRendering, Q3View_StartPicking, Q3View_StartBoundingBox, or Q3View_StartBoundingSphere). This allows you to have only one traversal loop defined as a function in your application, if you so desire. ErBox_Pick ErDisplayGroup_Pick ErGeneralPolygon_Pick ErGeometry_Pick ErLine_Pick ErMarker_Pick ErNURBCurve_Pick ErNURBPatch_Pick ErPoint_Pick ErPolygon_Pick ErTriGrid_Pick ErTriangle_Pick • Attributes were collapsed into a single type and some attributes were removed. ErAttributeSet_Compact ErAttributeSet_GetCSGEquation ErAttributeSet_GetConstructiveSolidGeometryID ErAttributeSet_GetType ErAttribute_Delete ErAttribute_Dispose ErFaceAttributeSet_New ErFaceAttributeSet_SizedNew ErGeometryAttributeSet_New ErGeometryAttributeSet_SizedNew ErVertexAttributeSet_New ErVertexAttributeSet_SizedNew ErViewAttributeSet_New ErViewAttributeSet_SizedNew • Function names were cleaned up and made consistent: Functions of type FooData_Empty are now Foo_EmptyData ErBoxData_Empty ErCStringData_Empty ErGeneralPolygonData_Empty ErHitData_Empty ErLineData_Empty ErMarkerData_Empty ErNURBCurveData_Empty ErNURBPatchData_Empty ErPointData_Empty ErPolygonData_Empty ErTriGridData_Empty ErTriangleData_Empty ErUnknownBinaryData_Empty ErUnknownTextData_Empty The function to create a renderer based on a type has changed ErRenderer_New Q3Renderer_NewFromType • The following calls have been removed: ErController_Decomission ErController_MoveTracker ErDrawContext_ClearImageBuffer ErDrawContext_GetActiveBuffer ErDrawContext_GetClearImageState ErDrawContext_SetActiveBuffer ErDrawContext_SetClearImageState ErDrawContext_UpdateFrontBuffer ErElementClass_GetElementSize ErFile_Open ErGeneralPolygon_GetContourAttributeSet ErGeneralPolygon_SetContourAttributeSet ErLightGroup_FindLight ErMatrix3x3_SetRotateAboutPoint_Deg ErMatrix4x4_SetRotateAboutAxis_Deg ErMatrix4x4_SetRotateAboutPoint_Deg ErMatrix4x4_SetRotate_XYZ_Deg ErMatrix4x4_SetRotate_X_Deg ErMatrix4x4_SetRotate_Y_Deg ErMatrix4x4_SetRotate_Z_Deg ErMesh_PickHitGetInfo ErOrderedDisplayGroup_CountObjectType ErPick_GetFirstHit ErPick_GetNextHit ErPick_GetPreviousHit ErPoint3D_To2D ErQuaternion_SetRotateAboutAxis_Deg ErQuaternion_SetRotateXYZ_Deg ErQuaternion_SetRotateX_Deg ErQuaternion_SetRotateY_Deg ErQuaternion_SetRotateZ_Deg ErRenderer_New ErRenderer_SetIsBoundingBoxVisibleFunc ErTracker_GetAbsolute ErTracker_GetCoordinates ErTracker_SetAbsolute ErTracker_SetCoordinates Explanation: ErController_Decomission Renamed to ErController_Decommission. ErController_MoveTracker Replaced by the calls: ErController_GetTrackerPosition ErController_SetTrackerPosition ErController_MoveTrackerPosition ErController_GetTrackerOrientation ErController_SetTrackerOrientation ErController_MoveTrackerOrientation ErDrawContext_ClearImageBuffer This operation was tied too closely to certain types of renderers and could not be supported by others or by certain HW accelerators. The scene is cleared now as part of the Q3View_StartRendering call. ErDrawContext_GetActiveBuffer ErDrawContext_SetActiveBuffer These calls dependent on certain features which can not be supported by certain types of accelerators/renderers. The double buffer state variable in the DrawContext controls the destination buffer. ErDrawContext_GetClearImageState ErDrawContext_SetClearImageState These calls were redundant and their functionality is absorved by the ClearImageMethod in the DrawContext. ErDrawContext_UpdateFrontBuffer This operation was tied too closely to certain types of renderers and could not be supported by others or by certain HW accelerators. The front buffer is now updated as part of the Q3View_EndRendering call. Please read the description for Q3Renderer_Sync and Q3Renderer_Flush in the documentation. ErElementClass_GetElementSize <need explanation> ErFile_Open This function has been split into two, Q3File_OpenRead and Q3File_OpenWrite. ErGeneralPolygon_GetContourAttributeSet ErGeneralPolygon_SetContourAttributeSet General polygons no longer have attribute sets per contour (didn't make sense) ErLightGroup_FindLight <need explanation> ErMatrix3x3_SetRotateAboutPoint_Deg ErMatrix4x4_SetRotateAboutAxis_Deg ErMatrix4x4_SetRotateAboutPoint_Deg ErMatrix4x4_SetRotate_XYZ_Deg ErMatrix4x4_SetRotate_X_Deg ErMatrix4x4_SetRotate_Y_Deg ErMatrix4x4_SetRotate_Z_Deg You need to use the radians version of these functions. ErMesh_PickHitGetInfo Removed in favor of the new ShapePart object. ErOrderedDisplayGroup_CountObjectType <need explanation> ErPick_GetFirstHit Removed in favor of the original, and more useful, ErPick_GetHitData ErPick_GetNextHit Removed in favor of the original, and more useful, ErPick_GetHitData ErPick_GetPreviousHit Removed in favor of the original, and more useful, ErPick_GetHitData ErPoint3D_To2D Superseded by ErRationalPoint3D_To2D ErQuaternion_SetRotateAboutAxis_Deg ErQuaternion_SetRotateXYZ_Deg ErQuaternion_SetRotateX_Deg ErQuaternion_SetRotateY_Deg ErQuaternion_SetRotateZ_Deg You need to use the radians version of these functions. ErRenderer_SetIsBoundingBoxVisibleFunc <need explanation> ErTracker_GetAbsolute ErTracker_SetAbsolute The notion of absolute trackers has been handled by usage of the ErTracker_GetPosition and ErTracker_GetOrientation routines. These can either return both the absolute and relative contributions to motion, or return the absolute and relative combined contributions. ErTracker_GetCoordinates This call has been split into ErTracker_GetPosition and ErTracker_GetOrientation. ErTracker_SetCoordinates This call has been split into ErTracker_SetPosition for absolute contributions to position, ErTracker_MovePosition for relative position, ErTracker_SetOrientation for absolute rotation and ErTracker_MoveOrientation for relative orientation. HARDWARE ACCELERATION Hardware acceleration happens "for free". All you need to do is use the interactive renderer: renderer = Q3Renderer_NewFromType (kQ3RendererTypeInteractive); And to make the images coherent, set up the drawContext to be double buffered. In addition, some hardware rasterizer engines (such as Apple's) can actually make coherent images without double buffering. This can provide a significant speed advantage, at the possible cost of some tearing. To take advantage of such hardware, you keep the drawContext double buffered (to say that you want the images coherent) and make the call Q3InteractiveRenderer_SetDoubleBufferBypass (renderer, kQ3True); In the unlikely event that you want to use a particular rasterizer with the interactive renderer, you can set a "preference" with the call Q3InteractiveRenderer_SetPreferences (renderer, vendor, engine); where vendor and engine are from QD3DAcceleration.h. When we want to show the difference between hardware and software rasterization, we use this call to "prefer" the software rasterizer, or to just us the best available rasterizer. TEXTURE MAP STORAGE You can use the texture map memoryStorage object to either keep the pixels in "your domain" or "QD3D's domain". That is either you can keep the buffer (and modify it, e. g. for playing a QuickTime movie), or you can let set up the image, then have QD3D copy it, then throw away your copy. The former is better for animating texture maps, the latter requires less bookkeeping on your part. In either case, you set up a TQ3StoragePixMap with storagePixMap.image = Q3MemoryStorage_New (<see below>); storagePixMap.width = width; storagePixMap.height = height; storagePixMap.rowBytes = rowBytes; storagePixMap.pixelSize = 32; // the only size supported storagePixMap.pixelType = kQ3PixelTypeRGB32; // the only type supported storagePixMap.bitOrder = kQ3EndianBig; // the only order supported storagePixMap.byteOrder = kQ3EndianBig; // the only order supported To keep the image in your domain (and incur no copy overhead) you should make the memoryStorage object point to your buffer: <create the off-screen gWorld> <image into the gWorld> baseAddr = <baseAddr of the gWorld pixMap> size = <rowBytes of the gWorld pixMap> * <height of pixMap> storagePixMap.image = Q3MemoryStorage_New (baseAddr, size, size); then DO NOT dispose of the gWorld. To animate the texture map: <image into the gWorld> Q3MemoryStorage_SetBuffer (storagePixMap.image, baseAddr, size, size); The _SetBuffer call tells QD3D that the image has changed. This may be necessary to force any caches to be rebuilt. On the other hand, to keep your bookkeeping to a minimum: <create the off-screen gWorld> <image into the gWorld> baseAddr = <baseAddr of the gWorld pixMap> size = <rowBytes of the gWorld pixMap> * <height of pixMap> storagePixMap.image = Q3MemoryStorage_New (NULL, 0, 0); Q3MemoryStorage_Set (storagePixMap.image, baseAddr, size); <dispose of the gWorld> The _Set call copies the memory at baseAddr into memory that QD3D allocates. Known Bugs If you are using a Storage object which relies on a file reference number, you will have problems trying to open a file after writing it out. The workaround is to quit your app and open the file after launching again. There is a memory allocation problem, where we allocate more memory than what is needed. There is no workaround and a fix has been implemented for the next release. Mesh’s edge attributes are not being honored. In general, low memory conditions are not always handled gracefully. They will for the B2 release. Parameters are not always validated, so invalid parameters may cause a crash. Full parameter validation, specially for the debug version, is going to be in for B2.